This PR adds a new force_mode_constant parameter to EmissionsTracker that allows users to bypass psutil completely and use constant CPU power estimation instead. This addresses significant performance overhead issues where psutil.cpu_percent(interval=0.5) calls were causing 10x+ slowdowns in ML training workflows.

Problem

Users reported severe performance overhead when tracking short ML training iterations:

• Without CodeCarbon: 11 seconds
• With CodeCarbon v3.0.2: 1 minute 55 seconds (10x slower!)

The overhead was caused by repeated psutil.cpu_percent(interval=0.5) calls that take 0.5 seconds each. Additionally, uninstalling psutil to force fallback mode resulted in ModuleNotFoundError due to unconditional imports.

Solution

1. Graceful psutil imports

Made psutil imports conditional in codecarbon/core/cpu.py and codecarbon/core/util.py:

try:
    import psutil
    PSUTIL_AVAILABLE = True
except ImportError:
    PSUTIL_AVAILABLE = False
    psutil = None

2. New force_mode_constant parameter

Added force_mode_constant parameter to bypass psutil entirely:

# Bypass psutil completely - eliminates 0.5s overhead per measurement
tracker = EmissionsTracker(force_mode_constant=True)

# Works with custom CPU power for better accuracy
tracker = EmissionsTracker(
    force_mode_constant=True, 
    force_cpu_power=100  # 100W TDP
)

3. Updated CPU tracking logic

Modified codecarbon/core/resource_tracker.py to prioritize force_mode_constant before all other tracking methods, ensuring it completely bypasses psutil when enabled.

Features

• ✅ Zero psutil overhead: Completely eliminates psutil.cpu_percent() calls
• ✅ Graceful fallback: Handles missing psutil without crashing
• ✅ Custom power support: Works with force_cpu_power parameter
• ✅ Precedence control: Takes priority over force_mode_cpu_load
• ✅ Backward compatibility: No breaking changes to existing code
• ✅ Comprehensive testing: Full test suite covering all scenarios

Performance Impact

Testing shows successful elimination of psutil overhead:

• Normal mode: Uses CPU load tracking (slower due to psutil calls)
• Force constant mode: Uses constant power estimation (eliminates overhead)
• Both produce valid emissions measurements

Documentation

Added parameter documentation to docs/edit/parameters.rst:

* - force_mode_constant
  - | Force the use of constant mode for CPU power consumption measurement,
    | defaults to ``False``. When enabled, bypasses psutil completely and
    | uses a constant power consumption based on CPU TDP. Useful when
    | psutil overhead is significant or psutil is unavailable.

Fixes #878.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.